package cn.iocoder.yudao.module.reading.service.classes;

import cn.iocoder.yudao.module.reading.controller.app.classes.vo.*;
import cn.iocoder.yudao.module.reading.controller.app.punch.vo.PunchRecordRespVO;
import cn.iocoder.yudao.module.reading.dal.dataobject.classes.ClassDO;

import java.util.List;

/**
 * 班级管理 Service 接口
 *
 * @author 芋道源码
 */
public interface ClassService {

    // =============================================
    // 班级管理
    // =============================================

    /**
     * 获取用户班级列表
     *
     * @param userId 用户ID
     * @return 班级列表
     */
    List<ClassRespVO> getUserClasses(Long userId);

    /**
     * 获取班级详细信息
     *
     * @param classId 班级ID
     * @param userId  当前用户ID
     * @return 班级详情
     */
    ClassRespVO getClassDetail(Long classId, Long userId);

    /**
     * 创建班级
     *
     * @param userId      创建者ID
     * @param createReqVO 创建信息
     * @return 班级ID
     */
    Long createClass(Long userId, ClassCreateReqVO createReqVO);

    /**
     * 修改班级信息
     *
     * @param classId     班级ID
     * @param userId      操作用户ID
     * @param updateReqVO 更新信息
     */
    void updateClass(Long classId, Long userId, ClassUpdateReqVO updateReqVO);

    /**
     * 删除班级
     *
     * @param classId 班级ID
     * @param userId  操作用户ID
     */
    void deleteClass(Long classId, Long userId);

    // =============================================
    // 成员管理
    // =============================================

    /**
     * 获取班级成员列表（包括老师）
     *
     * @param classId 班级ID
     * @param userId  当前用户ID
     * @return 成员列表
     */
    List<ClassMemberRespVO> getClassMembers(Long classId, Long userId);

    /**
     * 获取班级学生成员列表（排除老师，用于打卡等功能）
     *
     * @param classId 班级ID
     * @param userId  当前用户ID
     * @return 学生成员列表
     */
    List<ClassMemberRespVO> getClassStudents(Long classId, Long userId);

    /**
     * 移除班级成员
     *
     * @param classId      班级ID
     * @param targetUserId 要移除的用户ID
     * @param operatorId   操作者ID
     */
    void removeMember(Long classId, Long targetUserId, Long operatorId);

    /**
     * 加入班级
     *
     * @param userId      用户ID
     * @param joinReqVO   加入信息
     * @return 班级ID
     */
    Long joinClass(Long userId, JoinClassReqVO joinReqVO);

    /**
     * 切换当前班级
     *
     * @param userId        用户ID
     * @param switchReqVO   切换信息
     */
    void switchCurrentClass(Long userId, SwitchClassReqVO switchReqVO);

    // =============================================
    // 班级打卡
    // =============================================

    /**
     * 班级打卡
     *
     * @param classId     班级ID
     * @param userId      用户ID
     * @param punchReqVO  打卡信息
     */
    void classPunch(Long classId, Long userId, ClassPunchReqVO punchReqVO);

    /**
     * 获取班级打卡记录
     *
     * @param classId 班级ID
     * @param userId  当前用户ID
     * @return 打卡记录列表
     */
    List<PunchRecordRespVO> getClassPunchRecords(Long classId, Long userId);

    // =============================================
    // 班级口令管理
    // =============================================

    /**
     * 生成班级口令
     *
     * @return 班级口令
     */
    String generateClassCode();

    /**
     * 验证班级口令
     *
     * @param classCode 班级口令
     * @return 验证结果
     */
    ClassCodeVerifyRespVO verifyClassCode(String classCode);

    // =============================================
    // 班级高级管理
    // =============================================

    /**
     * 转让班级管理权
     *
     * @param classId       班级ID
     * @param operatorId    操作者ID
     * @param transferReqVO 转让信息
     */
    void transferClass(Long classId, Long operatorId, TransferClassReqVO transferReqVO);

    /**
     * 锁定/解锁班级
     *
     * @param classId     班级ID
     * @param operatorId  操作者ID
     * @param lockReqVO   锁定信息
     */
    void lockClass(Long classId, Long operatorId, LockClassReqVO lockReqVO);

    // =============================================
    // 辅助方法
    // =============================================

    /**
     * 获取班级信息
     *
     * @param classId 班级ID
     * @return 班级信息
     */
    ClassDO getClass(Long classId);

    /**
     * 检查用户是否为班级管理员
     *
     * @param classId 班级ID
     * @param userId  用户ID
     * @return 是否为管理员
     */
    boolean isClassCreator(Long classId, Long userId);

    /**
     * 检查用户是否为班级成员
     *
     * @param classId 班级ID
     * @param userId  用户ID
     * @return 是否为成员
     */
    boolean isClassMember(Long classId, Long userId);

    /**
     * 检查用户是否为多个班级的创建者
     *
     * @param classIds 班级ID列表
     * @param userId   用户ID
     * @return 是否为所有班级的创建者
     */
    boolean isMultiClassCreator(List<Long> classIds, Long userId);

    /**
     * 验证多个班级是否存在
     *
     * @param classIds 班级ID列表
     * @throws ServiceException 如果有班级不存在
     */
    void validateMultiClassExists(List<Long> classIds);

}
